Skip to content

Conversation

@Curtis-Barnhart
Copy link
Contributor

Resolves #401

Issue 401 describes how the time_scale member of Engine can be changed to significantly speed up some types of tests (it can cause timing issues with others, so it should be used carefully). bitwes mentioned there that it would be good to have something built in to gut that could reset this value after tests were run so unexpected Engine time scales wouldn't bleed into other code.

This PR adds a member and two methods to the GutTest class that allow users to easily modify the Engine time scale for individual tests inside that test's code without needing to worry about cleaning up values. To change the time scale of any given test:

class ExampleTest:
    extends GutTest

    func test_something():
        set_time_scale(5.0)
        await wait_seconds(5.0)
        # By now, about 1 second has passed

This set_time_scale method can also be called inside before_each so that every method in a test runs on a given time scale. The time scale can also be set to multiple different values multiple times within a single test method, and after the method ends, it will always be reset to the original Engine value before the first set_time_scale was called. The other method is time_scale_reset which resets the time scale set through set_time_scale and can be called anytime during the test method by the user as well.

I will also regenerate the class reference as well as update the wiki documentation if this approach in the code is to your liking - I didn't want to write up a wiki description of how it worked until I knew that the approach was actually final, haha. Does this seem like an acceptable solution to the ideas proposed in 401?

@bitwes
Copy link
Owner

bitwes commented Jan 5, 2026

I like the idea, but in reading up on time_scale, I think it has too many caveats to manage this in GUT. As soon as we add a wrapper, users tend to think "you let me do this, why aren't you protecting me from myself?" I'd want to know a ton more about how things can go wrong before making this a feature of GUT.

Maybe a Tips/Tricks page would be a good place to start. We could put in an example FastTest class with a lot of warnings and links to Godot docs. Maybe a call-to-action to give feedback if they have any success with this approach.

class_name MyFastTest
extends GutTest
var default_time_scale := Engine.get_time_scale() # or just 1.0
# add in physics and maybe audio ticks as well.
var fast_scale := 2.0

func before_each():
   # Having a way to disable fast tests is probably a good idea.
   if(MyGlobalsSomewhere.use_fast_tests):   
      Engine.set_time_scale(fast_ticks)

func after_each():
   Engine.set_time_scale(default_time_scale)

func after_all():
   Engine.set_time_scale(default_time_scale)
extends MyFastTest

func before_all():
    fast_scale = 4.5

func before_each():
   super()
   ...
func after_each():
   super()
   ...
func after_all():
   super()
   ...

<example tests>

This might also be good place to reference the hooks described here (but not yet added to the documentation). Being able to also reset the scales after a script has finished running (just in case something goes really wrong in a test script) would be good.

I'm most concerned about what it looks like to keep time_scale and physics_ticks_per_second synced to reasonable values across different platforms/environments. Especially when CI/CD pipelines are involved. This could all work fine locally but the pipeline becomes very flakey.

Note: It's recommended to keep this property above 0.0, as the game may behave unexpectedly otherwise.

Note: This does not affect audio playback speed. Use AudioServer.playback_speed_scale to adjust audio playback speed independently of Engine.time_scale.

Note: This does not automatically adjust physics_ticks_per_second. With values above 1.0 physics simulation may become less precise, as each physics tick will stretch over a larger period of engine time. If you're modifying Engine.time_scale to speed up simulation by a large factor, consider also increasing physics_ticks_per_second to make the simulation more reliable.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

No mentions of Engine.set_time_scale

2 participants